Greptile Summary

This PR fixes a CPU usage graph that was permanently pinned at 100% by introducing a separate cpuSecondsIdle counter (idle + iowait modes) throughout the full stack — agent scraper, Go structs, heartbeat payload, Zod schema, Prisma model + migration, tRPC select, and frontend chart — and replacing the old wall-clock-time formula with (totalDelta - idleDelta) / totalDelta * 100.

• Root cause fix is correct: the old approach divided accumulated CPU-seconds (all cores × all modes) by elapsed wall-clock seconds, which always exceeded 1.0 × 100% for multi-core hosts. The new ratio-based formula is the standard way to compute CPU utilization from host_cpu_seconds_total counters.
• iowait is grouped into the idle bucket (scraper.go lines 150-152). This is a semantic trade-off: I/O-bound workloads will report lower CPU%, which could mask disk pressure. Consider whether surfacing iowait separately or documenting the choice is warranted.
• Backward compatibility is handled correctly: old agents without cpuSecondsIdle send 0, the DB column defaults to 0, and the frontend clamps the result — reproducing the prior 100% display until agents update, as documented in the PR.
• Migration is safe: NOT NULL DEFAULT 0 on a DOUBLE PRECISION column is a non-destructive, backward-compatible change for existing rows.
• Minor indentation error in heartbeat.go: the new CpuSecondsIdle field is indented one tab level shallower than all surrounding fields; gofmt would flag this.

Confidence Score: 4/5

• Safe to merge — the core formula change is mathematically correct and the full-stack propagation is consistent.
• The fix correctly addresses the root cause, all layers are updated consistently, backward compatibility is maintained, and the migration is non-destructive. Score is 4 rather than 5 only because of the iowait semantic ambiguity and the minor gofmt indentation issue in heartbeat.go.
• agent/internal/metrics/scraper.go (iowait classification) and agent/internal/agent/heartbeat.go (indentation)

Important Files Changed

Sequence Diagram

sequenceDiagram
    participant V as Vector (Prometheus)
    participant S as scraper.go
    participant H as heartbeat.go
    participant API as /api/agent/heartbeat
    participant DB as PostgreSQL (NodeMetric)
    participant FE as node-metrics-charts.tsx

    V->>S: host_cpu_seconds_total{mode="idle"} += x
    V->>S: host_cpu_seconds_total{mode="iowait"} += y
    V->>S: host_cpu_seconds_total{mode="user"} += z
    note over S: CpuSecondsTotal += all modes<br/>CpuSecondsIdle += idle + iowait
    S->>H: HostMetrics{CpuSecondsTotal, CpuSecondsIdle}
    H->>API: POST heartbeat {cpuSecondsTotal, cpuSecondsIdle}
    API->>API: Zod validate (both optional)
    API->>DB: NodeMetric.create({cpuSecondsTotal, cpuSecondsIdle})
    FE->>DB: fleet.nodeMetrics query (cpuSecondsTotal, cpuSecondsIdle selected)
    DB-->>FE: time-series rows
    note over FE: cpuPercent = (totalDelta - idleDelta) / totalDelta * 100<br/>clamped to [0, 100]

_{Last reviewed commit: 1663a49}